<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
      <title>2. Description</title>
      <meta charset="utf-8" />
      <meta name="generator" content="DocBook XSL 2.0 Stylesheets V2.5.0" />
      <link href="css/default.css" rel="stylesheet" type="text/css" />
      <link href="css/db-prism.css" rel="stylesheet" type="text/css" />
      <link rel="stylesheet" href="css/xproc.css" type="text/css" /><script type="text/javascript" src="js/dbmodnizr.js"></script></head>
   <body>
      <div class="page">
         <div class="content">
            <div xmlns:tmpl="http://docbook.org/xslt/titlepage-templates" class="navheader">
               <table border="0" cellpadding="0" cellspacing="0" width="100%" summary="Navigation table">
                  <tr>
                     <td align="left"> <a title="XML Calabash Reference" href="index.html"><img src="img/home.png" alt="Home" border="0" /></a> <a href="antsetup.html" title="1 .  Setting up the Ant Task and Types"><img src="img/prev.png" alt="Prev" border="0" /></a> <a title="Chapter  3 .  Calabash Ant Task" href="anttask.html"><img src="img/up.png" alt="Up" border="0" /></a> <a title="3 .  Parameters" href="antparam.html"><img src="img/next.png" alt="Next" border="0" /></a></td>
                     <td align="right"><i>XML Calabash Reference</i> (Version 0.28)</td>
                  </tr>
               </table>
            </div>
            <div class="body">
               <section id="antdesc" class="section">
                  <div class="section-titlepage">
                     <h2>2. Description</h2>
                  </div>
                  <div class="content">
                     <p>Runs Calabash.  You can use this task to process:
                        <div class="itemizedlist">
                           <ul>
                              <li>
                                 <p>A single input file to produce a single output
                                    file</p>
                              </li>
                              <li>
                                 <p>A set of input files, processed one at a time, to
                                    produce a set of output files</p>
                              </li>
                              <li>
                                 <p>Multiple input files as the input to one XProc
                                    input port processed to produce a single output
                                    file</p>
                              </li>
                              <li>
                                 <p>Any of the above with additional input ports to
                                    each of which are applied one or more input files
                                    whose file names may be either fixed or mapped
                                    from the name(s) of the current main input
                                    file(s)</p>
                              </li>
                              <li>
                                 <p>Any of the above with additional output ports
                                    whose file names may be either fixed or mapped
                                    from the name(s) of the current main input
                                    file(s)</p>
                              </li>
                           </ul>
                        </div>
                     </p>
                     <p>You can also specify options and parameters to be used by the
                        pipeline.</p>
                     <section id="antdesc.4" class="section">
                        <div class="section-titlepage">
                           <h3>2.1. Custom Task and Types</h3>
                        </div>
                        <div class="content">
                           <p>The previously defined Antlib provides one custom task and four
                              custom types in the configured namespace.</p>
                           <section id="antdesc.4.3" class="section">
                              <div class="section-titlepage">
                                 <h4>2.1.1. calabash</h4>
                              </div>
                              <div class="content">
                                 <p>The custom Ant Task that is provided by the Antlib.
                                    This is the main piece of the Calabash Ant integration.
                                    The remaining sections of this chapter describe the
                                    usage of this task.</p>
                              </div>
                           </section>
                           <section id="antdesc.4.4" class="section">
                              <div class="section-titlepage">
                                 <h4>2.1.2. stdin</h4>
                              </div>
                              <div class="content">
                                 <p>A read-only Ant Resource that connects to stdin.</p>
                              </div>
                           </section>
                           <section id="antdesc.4.5" class="section">
                              <div class="section-titlepage">
                                 <h4>2.1.3. stdout</h4>
                              </div>
                              <div class="content">
                                 <p>A write-only Ant Resource that connects to stdout.</p>
                              </div>
                           </section>
                           <section id="antdesc.4.6" class="section">
                              <div class="section-titlepage">
                                 <h4>2.1.4. stdinout</h4>
                              </div>
                              <div class="content">
                                 <p>A read-write Ant Resource that connects to stdin
                                    for reading and to stdout for writing.</p>
                              </div>
                           </section>
                           <section id="antdesc.4.7" class="section">
                              <div class="section-titlepage">
                                 <h4>2.1.5. stderr</h4>
                              </div>
                              <div class="content">
                                 <p>A write-only Ant Resource that connects to stderr.</p>
                              </div>
                           </section>
                        </div>
                     </section>
                     <section id="ant.input-and-output" class="section">
                        <div class="section-titlepage">
                           <h3>2.2. Input and output files and filesets</h3>
                        </div>
                        <div class="content">
                           <p>In the simplest scenario, the <code class="tag-attribute">in</code>
                              attribute, if present, specifies the single input file and / or
                              the <code class="tag-attribute">out</code> attribute, if present,
                              specifies the single output file.  The <code class="tag-attribute">inPort</code> and <code class="tag-attribute">outPort</code>
                              attributes specify the pipeline port to which to apply the input
                              or from which to receive the output, respectively, though these
                              may be omitted as stated below.</p>
                           <p>You can as well or instead specify one or more files to apply to an
                              input port using one or more nested <code class="tag-element">input</code> elements.</p>
                           <p><code class="tag-element">input</code> elements whose <code class="tag-attribute">port</code> attribute value matches
                              <code class="tag-attribute">inPort</code> (or whose <code class="tag-attribute">port</code> attribute is omitted when
                              <code class="tag-attribute">inPort</code> is omitted) are
                              applied to the <code class="tag-attribute">inPort</code> port.  Those
                              <code class="tag-element">input</code> elements may contain
                              zero or more <a href="http://ant.apache.org/manual/Types/resources.html">Ant resources</a>
                              (i.e., <code class="tag-element">fileset</code>, <code class="tag-element">dirset</code>, etc.).</p>
                           <p><code class="tag-element">input</code> elements for ports other than the
                              <code class="tag-attribute">inPort</code> port may contain
                              either zero or more <a href="http://ant.apache.org/manual/Types/resources.html">Ant resources</a> or an Ant
                              mapper element (i.e., <code class="tag-element">mapper</code>, <code class="tag-element">globmapper</code>, etc.) that maps the
                              current <code class="tag-attribute">inPort</code> file(s) name(s) to
                              other file name(s) that are used as the input file(s) for that
                              port. You cannot specify both Ant resources and a mapper
                              for an input port (nor can you specify a mapper for the <code class="tag-attribute">inPort</code> port).</p>
                           <p>You can as well or instead specify a file to contain the output of
                              an output port using one or more nested <code class="tag-element">output</code> elements. You cannot specify more than
                              one <code class="tag-element">output</code> element for any pipeline
                              output.</p>
                           <p>An <code class="tag-element">output</code> element whose <code class="tag-attribute">port</code> attribute value matches
                              <code class="tag-attribute">outPort</code> (or whose <code class="tag-attribute">port</code> attribute is omitted when
                              <code class="tag-attribute">outPort</code> is omitted) is
                              used for the <code class="tag-attribute">outPort</code> port. This
                              <code class="tag-element">output</code> element and the <code class="tag-attribute">out</code> attribute cannot both be
                              used at once.</p>
                           <p>Other <code class="tag-element">output</code> elements may each be used
                              for any of the other output ports of the pipeline.</p>
                           <p><code class="tag-attribute">output</code> elements may contain either
                              zero or more <a href="http://ant.apache.org/manual/Types/resources.html">Ant resources</a> or an Ant mapper
                              element (i.e., <code class="tag-element">mapper</code>, <code class="tag-element">globmapper</code>, etc.) that maps the
                              current <code class="tag-attribute">inPort</code> file(s) name(s) to a
                              file name that is used as the output file for that port.  You
                              cannot specify both Ant resources and a mapper for an
                              output port, and the <code class="tag-element">output</code> cannot
                              result in more than one file name.</p>
                           <p>When no files are specified for either the <code class="tag-attribute">inPort</code> or <code class="tag-attribute">outPort</code>
                              ports, the implicit fileset (formed based on <code class="tag-attribute">includes</code> and other attributes
                              of <code class="tag-element">calabash</code>) and / or an explicit file
                              set (formed from nested <a href="http://ant.apache.org/manual/Types/resources.html">Ant resources</a> (outside of
                              any <code class="tag-element">input</code> or <code class="tag-element">output</code> elements) makes a set of files that are
                              processed one at a time as the input to the <code class="tag-attribute">inPort</code> port in separate runs of
                              the pipeline.</p>
                           <p>The <code class="tag-attribute">basedir</code>, <code class="tag-attribute">includes</code>, <code class="tag-attribute">includesfile</code>, <code class="tag-attribute">excludes</code>, <code class="tag-attribute">excludesfile</code>, <code class="tag-attribute">defaultexcludes</code>, and <code class="tag-attribute">scanincludeddirectories</code> attributes determine the
                              implicit fileset.  <code class="tag-attribute">useimplicitfileset</code> can disable the implicit
                              fileset.</p>
                           <p>When the implicit fileset and / or the explicit fileset selects one
                              or more files, the <code class="tag-attribute">destdir</code>, and
                              <code class="tag-attribute">extension</code> attributes (or
                              using a nested mapper instead of <code class="tag-attribute">extension</code>) determine the filename to use for the
                              output of the <code class="tag-attribute">outPort</code> port, and the
                              <a href="http://ant.apache.org/manual/Types/resources.html">Ant resources</a>
                              or mapper for other input and output ports
                              determine the file(s) from which to read or the file to which to
                              write for those ports.</p>
                        </div>
                     </section>
                     <section id="antdesc.6" class="section">
                        <div class="section-titlepage">
                           <h3>2.3. Ports</h3>
                        </div>
                        <div class="content">
                           <p>The <code class="tag-attribute">inPort</code> and <code class="tag-attribute">outPort</code> attributes determine the pipeline ports
                              to use for single, or sequential, processing of files.
                              Additionally, the filename of the file on the <code class="tag-attribute">inPort</code> port is used (or can be
                              used) by mappers to determine the input or output files to use
                              for other ports.</p>
                           <p>You may omit at most one input port name and at most one output
                              port name from the ports specified on the <code class="tag-element">calabash</code> task. The <code class="tag-element">calabash</code> task maps the primary non-parameter
                              input the primary output port of the pipeline to the
                              unnamed ports (and any additional port without a defined mapping
                              will cause an error). The omitted ports do not have to be the
                              <code class="tag-attribute">inPort</code> and <code class="tag-attribute">outPort</code> ports; e.g., you can
                              instead specify <code class="tag-attribute">inPort</code> and omit the
                              <code class="tag-attribute">port</code> attribute on the
                              nested <code class="tag-element">input</code> element for a different
                              port.</p>
                           <p>Nested <code class="tag-element">parameter</code> elements specify Inputs
                              to parameter ports.</p>
                        </div>
                     </section>
                  </div>
               </section>
            </div>
         </div>
         <div xmlns:tmpl="http://docbook.org/xslt/titlepage-templates" class="navfooter">
            <table width="100%" summary="Navigation table">
               <tr>
                  <td width="40%" align="left"><a title="1 .  Setting up the Ant Task and Types" href="antsetup.html"><img src="img/prev.png" alt="Prev" border="0" /></a> </td>
                  <td width="20%" align="center"><a title="XML Calabash Reference" href="index.html"><img src="img/home.png" alt="Home" border="0" /></a></td>
                  <td width="40%" align="right"> <a title="3 .  Parameters" href="antparam.html"><img src="img/next.png" alt="Next" border="0" /></a></td>
               </tr>
               <tr>
                  <td width="40%" align="left">1 .  Setting up the Ant Task and Types </td>
                  <td width="20%" align="center"><a title="Chapter  3 .  Calabash Ant Task" href="anttask.html"><img src="img/up.png" alt="Up" border="0" /></a></td>
                  <td width="40%" align="right"> 3 .  Parameters</td>
               </tr>
            </table>
         </div>
         <div xmlns:tmpl="http://docbook.org/xslt/titlepage-templates" class="copyrightfooter">
            <p><a href="dbcpyright.html">Copyright</a> © 2011–2020 Norman Walsh.</p>
         </div>
      </div>
   </body>
</html>